docs(ai): clearer guidance on sync tests#376
Merged
Merged
Conversation
AI agents were failing to discover and use the generate-completions.sh script when sync tests failed, instead attempting to manually regenerate completion files through various wrong approaches. This adds the script to the AI instructions so agents know about it before encountering failures, and adds general guidance to follow the exact commands that sync test error messages provide. https://claude.ai/code/session_01Bxeem6wsV2g7vNLQRRHodx
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repository’s AI/contributor instruction docs to reduce CLI-doc drift and to make “sync test” failures easier to resolve by following the command shown in the test output.
Changes:
- Add explicit guidance to run
./generate-completions.shafter CLI/help/output changes, and to avoid manual regeneration of generated CLI artifacts. - Clarify test-running guidance: when sync tests fail, read the error and run the exact command it instructs.
- Apply the same updates consistently across the shared template and the generated instruction files.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| template/ai-instructions/shared.md | Adds CLI artifact regeneration and sync-test failure handling guidance to the shared instruction template. |
| .github/copilot-instructions.md | Mirrors the updated guidance for GitHub Copilot instructions. |
| AGENTS.md | Mirrors the updated guidance for agent instructions. |
| CLAUDE.md | Mirrors the updated guidance for Claude-specific instructions. |
Performance Regression Reportscommit: a833ed8 There are no regressions. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR updates the AI instruction files across the repository to provide clearer guidance on CLI-related changes and test execution.
Changes made:
./generate-completions.shwhen CLI arguments, help text, or command-line output changes, with a strong warning against manual regeneration of completion files, help text, andUSAGE.md.github/copilot-instructions.mdAGENTS.mdCLAUDE.mdtemplate/ai-instructions/shared.mdRationale:
These changes ensure that AI assistants and contributors understand the importance of using automated scripts for CLI-related documentation generation and provide better guidance for handling test failures, reducing manual errors and improving consistency across the codebase.
https://claude.ai/code/session_01Bxeem6wsV2g7vNLQRRHodx